BEA Logo BEA WebLogic Server Release 1.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

   EJB 2.0 for BEA WebLogic Server:   Previous Topic   |   Next Topic   |   Contents   

 

EJB 2.0 for BEA WebLogic Server Reference

 

Overview

ejbc20

XML deployment properties

Manually editing XML deployment files

DOCTYPE header information

Document Type Definitions (DTDs) for validation

weblogic-ejb-jar.xml Properties

Index of WebLogic Server Deployment Elements

Overview

This section provides a complete reference to the new and updated utilities and support files supplied with EJB 2.0 for BEA WebLogic Server. It contains reference information for:

ejbc20

The installed ejb20.jar file includes the weblogic.ejbc20 utility for compiling EJB 2.0 container classes. If you compile .jar files for deployment into the EJB 2.0 container, you must use weblogic.ejbc20 to generate the container classes. To deploy .jars into the EJB 1.1 container, use the weblogic.ejbc utility that was installed with WebLogic Server Version 5.1, Service Pack 3.

Note: To use weblogic.ejbc20, you must place the ejbc20.jar file at the beginning of the Java classpath for your development environment. However, you must not place ejbc20.jar in the Java classpath that you use to start WebLogic Server.

weblogic.ejbc20 uses the same command line options and syntax as weblogic.ejbc. See weblogic.ejbc for details.

XML deployment properties

This section describes the new XML elements used to define deployment properties in the WebLogic Server EJB 2.0 container.

Manually editing XML deployment files

The WebLogic Server DeployerTool utility has not been updated to account for new EJB 2.0 deployment elements. To create and deploy message-driven beans, or use the new caching and clustering deployment elements, you must manually edit the XML deployment files using a text editor. See also Basic conventions for more information on the conventions to use when modifying XML deployment files.

DOCTYPE header information

When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose. The correct text for the PUBLIC element for each XML deployment file is as follows:

XML file

PUBLIC element string

ejb-jar.xml

`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' `http://java.sun.com/j2ee/dtds/ejb-jar_2_0.dtd'

weblogic-ejb-jar.xml

`-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN' `http://www.bea.com/servers/wls510/ejb20/dtd/weblogic-ejb-jar.dtd'

weblogic-cmp-rdbms
-jar.xml

`-//BEA Systems, Inc.//DTD WebLogic 5.1.0 EJB RDBMS Persistence//EN' `http://www.bea.com/servers/wls510/dtd/weblogic-rdbms-persistence.dtd'

For example, the entire DOCTYPE header for a weblogic-ejb-jar.xml file is as follows:

<!DOCTYPE weblogic-ejb-jar PUBLIC 
'-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN' 'http://www.bea.com/servers/wls510/ejb20/dtd/weblogic-ejb-jar.dtd'>

XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc20 or DeployerTool):

SAXException: This document may not have the identifier `identifier_name'

identifier_name generally includes the invalid text from the PUBLIC element.

Document Type Definitions (DTDs) for validation

The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server utilities ignore the DTDs embedded within the DOCTYPE header of XML deployment files, and instead use the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.

The following links provide the new public DTD locations for XML deployment files used with the WebLogic Server EJB 2.0 container:

weblogic-ejb-jar.xml Properties

weblogic-ejb-jar.xml defines EJB deployment properties unique to WebLogic Server. The Beta EJB 2.0 container uses a version of weblogic-ejb-jar.xml that is different from the one shipped with WebLogic Server Version 5.1. The revised DTD for weblogic-ejb-jar.xml includes new elements for enabling stateful session EJB replication, configuring entity EJB locking behavior, and assigning JMS Queue and Topic names for message-driven beans. The new DTD also reorganizes the major stanzas into more logical sections.

You can continue to use the earlier weblogic-ejb-jar.xml DTD for EJB 1.1 that you will deploy into the EJB 1.1 container. However, if you want to use any of the new EJB 2.0 features or deploy beans into the EJB 2.0 container, you must use the new DTD described below.

The top level elements in the EJB 2.0 weblogic-ejb-jar.xml are as follows:

Use the links above, or see XML deployment properties for more information about individual EJB 2.0 deployment stanzas and elements. See also XML deployment properties for complete information about the new deployment elements introduced for EJB 1.1.

Index of WebLogic Server Deployment Elements

ejb-name

Range of values:

name of an EJB defined in ejb-jar.xml

Default value:

n/a

Requirements:

Required element in method stanza.

Parent elements:

weblogic-enterprise-bean
transaction-isolation
method

Deployment file:

weblogic-ejb-jar.xml

Function

ejb-name specifies the name of an EJB to which WebLogic Server applies isolation level properties.

Example

See method.

ejb-reference-description

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean
reference-description

Deployment file:

weblogic-ejb-jar.xml

Function

The resource-description stanza maps a resource reference named defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.

Example

The resource-description stanza can contain additional elements as shown here:

<reference-descriptor>

  <ejb-reference-description>

    <ejb-ref-name>...</ejb-ref-name>

    <jndi-name>...</jndi-name>

  </ejb-reference-description>

</reference-descriptor>

ejb-ref-name

Range of values:

n/a

Default value:

n/a

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean
reference-description
ejb-reference-description

Deployment file:

weblogic-ejb-jar.xml

Function

The resource-description stanza maps a resource reference named defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.

Example

The resource-description stanza can contain additional elements as shown here:

<reference-descriptor>

  <ejb-reference-description>

    <ejb-ref-name>. . .</ejb-ref-name>

    <jndi-name>. . .</jndi-name>

  </ejb-reference-description>

</reference-descriptor>

enable-call-by-reference

Range of values:

true | false

Default value:

true

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean
reference-description

ejb-reference-description

Deployment file:

weblogic-ejb-jar.xml

Function

By default, EJB methods called from within the same server pass arguments by reference. This increases the performance of method invocation since parameters are not copied.

If you set enable-call-by-reference to "false," parameters to EJB methods are copied (pass by value) in accordance with the EJB 1.1 specification. Pass by value is always necessary when the EJB is called remotely (not from within the server).

Example

The following example enables pass by value for EJB methods:

<weblogic-enterprise-bean>

  <ejb-name>AccountBean</ejb-name>

  ...

  <enable-call-by-reference>false</enable-call-by-reference>

</weblogic-enterprise-bean>

entity-cache

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

The entity-cache stanza is optional, and is valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The entity-cache stanza defines properties used to cache entity EJB instances within WebLogic Server. See EJB Lifecycle in WebLogic Server for a general discussion of the caching services available in WebLogic Server.

Example

<entity-descriptor>

  <entity-cache>

    <max-beans-in-cache>...</max-beans-in-cache>

    <idle-timeout-seconds>...</idle-timeout-seconds>

    <read-timeout-seconds>...<read-timeout-seconds>

    <concurrency-strategy>...</concurrency-strategy>

  </entity-cache>

  <lifecycle>...</lifecycle>

  <persistence>...</persistence>

  <entity-clustering>...</entity-clustering>

</entity-descriptor>

entity-clustering

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element. Valid only for entity EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The entity-clustering stanza contains elements that determines how WebLogic Server replicates entity EJB instances in a cluster.

Example

The following excerpt shows the structure of a entity-clustering stanza:

<entity-clustering>

  <home-is-clusterable>true</home-is-clusterable>

  <home-load-algorithm>random</home-load-algorithm>

  <home-call-router-class-name>beanRouter</home-call-router-class-name>

</entity-clustering>

entity-descriptor

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

One entity-descriptor stanza is required for each entity EJB in the .jar.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The entity-descriptor stanza defines caching, clustering, and persistence properties for entity EJBs in WebLogic Server.

Example

The following example shows the structure of the entity-descriptor stanza:

<entity-descriptor>

  <entity-cache>...</entity-cache>

  <lifecycle>...</lifecycle>

  <persistence>...</persistence>

  <entity-clustering>...</entity-clustering>

</entity-descriptor>

concurrency-strategy

Range of values:

Exclusive | Database | ReadOnly

Default value:

Exclusive

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-cache

Deployment file:

weblogic-ejb-jar.xml

Function

This element determines ejbLoad() and ejbStore() behavior for entity EJB instances. You can set this element to one of three possible values:

See Setting the cache strategy for entity EJBs for more information on the Exclusive and Database locking behaviors. See Setting the cache strategy for entity EJBs for more information about read-only entity EJBs.

Example

The following entry identifies the AccountBean class as a read-only entity EJB:

<weblogic-enterprise-bean>

  <ejb-name>AccountBean</ejb-name>

  <entity-descriptor>

    <entity-cache>

      <concurrency-strategy>ReadOnly</concurrency-strategy>

    </entity-cache>

  </entity-descriptor>

</weblogic-enterprise-bean>

db-is-shared

Range of values:

true | false

Default value:

true

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

Deployment file:

weblogic-ejb-jar.xml

Function

The db-is-shared element applies only to entity beans. When set to "true" WebLogic Server assumes that EJB data could be modified between transactions and reloads data at the beginning of each transaction. When set to "false" WebLogic Server assumes that it has exclusive access to the EJB data in the persistent store. See Using db-is-shared to limit calls to ejbLoad() for more information.

Example

See persistence.

delay-updates-until-end-of-tx

Range of values:

true | false

Default value:

true

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

Deployment file:

weblogic-ejb-jar.xml

Function

Set this property to "true" (the default), to update the persistent store of all beans in a transaction at the completion of the transaction. This generally improves performance by avoiding unnecessary updates. However, it does not preserve the ordering of database updates within a database transaction.

If your datastore uses an isolation level of TRANSACTION_READ_UNCOMMITTED, you may want to allow other database users to view the intermediate results of in-progress transactions. In this case, set delay-updates-until-end-of-tx to "false" to update the bean's persistent store at the conclusion of each method invoke. See ejbLoad() and ejbStore() behavior for entity EJBs for more information.

Note: Setting delay-updates-until-end-of-tx to false does not cause database updates to be "committed" to the database after each method invoke; they are only sent to the database. Updates are committed or rolled back in the database only at the conclusion of the transaction.

Example

The following entry specifies that WebLogic Server call ejbStore() at the end of each method invocation:

<entity-descriptor>

  <persistence>

    <delay-updates-until-end-of-tx>false</delay-updates-until-end-of-tx>

  </persistence>

</entity-descriptor>

destination-jndi-name

Range of values:

valid JNDI name

Default value:

n/a

Requirements:

Required in message-driven-descriptor.

Parent elements:

weblogic-enterprise-bean
message-driven-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

destination-jndi-name specifies the JNDI name of an actual JMS Queue or Topic available in WebLogic Server.

Example

See message-driven-descriptor.

finders-call-ejbload

Range of values:

true | false

Default value:

true

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

Deployment file:

weblogic-ejb-jar.xml

Function

finders-call-ejbload determines whether WebLogic Server loads the EJB into the cache after a call to a finder method returns a reference to the bean. If you set this element to "false", WebLogic Server does not load automatically load the bean into the cache until the first method invocation; this behavior is consistent with the EJB 1.1 .specification.

Example

The following entry specifies that EJBs are loaded into the WebLogic Server cache automatically when a finder method returns a reference to the bean:

<entity-descriptor>

  <persistence>

    <finders-call-ejbload>true</finders-call-ejbload>

  </persistence>

</entity-descriptor>

home-call-router-class-name

Range of values:

Valid router class name

Default value:

n/a

Requirements:

Optional element. Valid only for entity EJBs and stateful session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-clustering

and

weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

home-call-router-class-name specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.extensions.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.

Example

See entity-clustering, stateful-session-clustering.

home-is-clusterable

Range of values:

true | false

Default value:

true

Requirements:

Optional element. Valid only for entity EJBs and stateful session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-clustering

and

weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

When home-is-clusterable is "true," the EJB can be deployed from multiple WebLogic Servers in a cluster. Calls to the home stub are load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call automatically fails over to another server hosting the bean.

Example

See entity-clustering, entity-clustering.

home-load-algorithm

Range of values:

round-robin | random | weight-based

Default value:

Value of weblogic.cluster.defaultLoadAlgorithm in weblogic.properties file

Requirements:

Optional element. Valid only for entity EJBs and stateful session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-clustering

and

weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

home-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.

You can define home-load-algorithm as one of the following values:

Example

See entity-clustering, stateful-session-clustering.

idle-timeout-seconds

Range of values:

1 to maxSeconds

Default value:

600

Requirements:

Optional element

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-cache

and

weblogic-enterprise-bean,
stateful-session-descriptor,
stateful-session-cache

Deployment file:

weblogic-ejb-jar.xml

Function

idle-timeout-seconds defines the maximum length of time a stateful EJB should remain in the cache. After this time has elapsed, WebLogic Server may remove the bean instance if the number of beans in cache approaches the limit of max-beans-in-cache. See EJB Lifecycle in WebLogic Server for more information.

Example

The following entry indicates that the stateful session EJB, AccountBean, should become eligible for removal if max-beans-in-cache is reached and the bean has been in cache for one 20 minutes:

<weblogic-enterprise-bean>

  <ejb-name>AccountBean</ejb-name>

  <stateful-session-descriptor>

    <entity-cache>

      <max-beans-in-cache>200</max-beans-in-cache>

      <idle-timeout-seconds>1200</idle-timeout-seconds>

    </entity-cache>

  </stateful-session-descriptor>

</weblogic-enterprise-bean>

initial-beans-in-free-pool

Range of values:

0 to maxBeans

Default value:

0

Requirements:

Optional element. Valid only for stateless session EJBs.

Parent elements:

weblogic-enterprise-bean,
transaction-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

If you specify a value for initial-bean-in-free-pool, WebLogic Server populates the free pool with the specified number of stateful session bean instances at startup. Populating the free pool in this way improves initial response time for the EJB, because initial requests for the bean can be satisfied without generating a new instance.

Example

See pool.

is-modified-method-name

Range of values:

valid entity EJB method name

Default value:

none

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

Deployment file:

weblogic-ejb-jar.xml

Function

is-modified-method-name specifies a method that WebLogic Server calls when the EJB is stored. The specified method must return a boolean value. If no method is specified, WebLogic Server always assumes that the EJB has been modified and always saves it.

Providing a method and setting it as appropriate can improve performance for EJB 1.1-compliant beans, and for beans that use bean-managed persistence. However, any errors in the method's return value can cause data inconsistency problems. See Using is-modified-method-name to limit calls to ejbStore() for more information.

Note: isModified() is no longer required for CMP entity EJBs based on the EJB 2.0 specification. When you deploy EJB 2.0 entity beans with container-managed persistence, WebLogic Server automatically detects which EJB fields have been modified, and writes only those fields to the underlying datastore.

Example

The following entry specifies that the EJB method named semidivine will queue WebLogic Server when as to when the EJB has been modified:

<entity-descriptor>

  <persistence>

    <is-modified-method-name>isModified</is-modified-method-name>

  </persistence>

</entity-descriptor>

isolation-level

Range of values:

Serializable | ReadCommitted | ReadUncommitted | RepeatableRead

Default value:

n/a

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean,
transaction-isolation

Deployment file:

weblogic-ejb-jar.xml

Function

isolation-level specifies the isolation level for all of the EJB's database operations. The following are possible values for isolation-level:

Refer to your database documentation for more information on the implications and support for different isolation levels.

Example

See transaction-isolation.

jndi-name

Range of values:

valid JNDI name

Default value:

n/a

Requirements:

Required in resource-description and ejb-reference-description.

Parent elements:

weblogic-enterprise-bean

and

weblogic-enterprise-bean
reference-description
resource-description

and

weblogic-enterprise-bean
reference-description
ejb-reference-description

Deployment file:

weblogic-ejb-jar.xml

Function

jndi-name specifies the JNDI name of an actual EJB or resource available in WebLogic Server.

Example

See resource-description and ejb-reference-description.

lifecycle

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

The lifecycle stanza is optional. lifecycle is valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor

and

weblogic-enterprise-bean

stateful-session-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The lifecycle stanza defines properties that affect the lifecycle of entity EJB instances within WebLogic Server. Currently, the lifecycle stanza includes only one element: passivation-strategy.

Example

<entity-descriptor>

  <lifecycle>

    <passivation-strategy>...</passivation-strategy>

  </lifecycle>

</entity-descriptor>

max-beans-in-cache

Range of values:

1 to maxBeans

Default value:

100

Requirements:

Optional element

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-cache

and

weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-cache

Deployment file:

weblogic-ejb-jar.xml

Function

The max-beans-in-cache element specifies the maximum number of objects of this class that are allowed in memory. When max-bean-in-cache is reached, WebLogic Server passivates some EJBs that have not been recently used by a client. max-beans-in-cache also affects when EJBs are removed from the WebLogic Server cache, as described in The WebLogic Server EJB container.

Example

The following entry enables WebLogic Server to cache a maximum of 200 instances of the AccountBean class:

<weblogic-enterprise-bean>

  <ejb-name>AccountBean</ejb-name>

  <entity-descriptor>

    <entity-cache>

      <max-beans-in-cache>200</max-beans-in-cache>

    </entity-cache>

  </entity-descriptor>

</weblogic-enterprise-bean>

max-beans-in-free-pool

Range of values:

0 to maxBeans

Default value:

max Int

Requirements:

Optional element. Valid only for stateless session EJBs.

Parent elements:

weblogic-enterprise-bean,
transaction-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

WebLogic Server maintains a free pool of EJBs for every stateless session bean class. The max-beans-in-free-pool element defines the size of this pool. By default, max-beans-in-free-pool has no limit; the maximum number of beans in the free pool is limited only by the available memory. See Stateful EJB lifecycle in The WebLogic Server EJB Container for more information.

Example

See pool.

message-driven-descriptor

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

One message-driven-descriptor stanza is required for each message-driven bean in the .jar.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The message-driven-descriptor stanza associates a message-driven bean with a JMS destination in WebLogic Server. This stanza currently includes only one XML element, destination-jndi-name.

Example

The following example shows the structure of the message-driven-descriptor stanza:

<message-driven-descriptor>

  <destination-jndi-name>...</destination-jndi-name>

</message-driven-descriptor>

method

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element. You can specify more than one method stanza to configure multiple EJB methods.

Parent elements:

weblogic-enterprise-bean

transaction-isolation

Deployment file:

weblogic-ejb-jar.xml

Function

The method stanza defines method-level transaction isolation settings for an EJB.

Example

The method stanza can contain the elements shown here:

<method>

  <description>...</description>

  <ejb-name>...</ejb-name>

  <method-intf>...</method-intf>

  <method-name>...</method-name>

  <method-params>...</method-params>

</method>

method-intf

Range of values:

Home | Remote

Default value:

n/a

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean
transaction-isolation
method

Deployment file:

weblogic-ejb-jar.xml

Function

method-intf specifies the EJB interface to which WebLogic Server applies isolation level properties. Use this element only if you need to differentiate between methods having the same signature in the EJB's home and remote interface.

Example

See method.

method-name

Range of values:

name of an EJB defined in ejb-jar.xml | *

Default value:

n/a

Requirements:

Required element in method stanza.

Parent elements:

weblogic-enterprise-bean
transaction-isolation
method

Deployment file:

weblogic-ejb-jar.xml

Function

method-name specifies the name of an individual EJB method to which WebLogic Server applies isolation level properties. Use the asterisk (*) to specify all methods in the EJB's home and remote interfaces.

If you specify a method-name, the method must be available in the specified ejb-name.

Example

See method.

method-param

Range of values:

Fully qualified Java type of a method parameter

Default value:

n/a

Requirements:

Required element in method-params.

Parent elements:

weblogic-enterprise-bean

transaction-isolation
method
method-params

Deployment file:

weblogic-ejb-jar.xml

Function

The method-param stanza specifies the fully-qualified Java type of a method parameter.

Example

See method-params.

method-params

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional stanza.

Parent elements:

weblogic-enterprise-bean

transaction-isolation
method

Deployment file:

weblogic-ejb-jar.xml

Function

The method-params stanza contains one or more elements that define the Java type name of each of the method's parameters.

Example

The method-params stanza contains one or more method-param elements, as shown here:

<method-params>

  <method-param>java.lang.String</method-param>

  ...

</method-params>

passivation-strategy

Range of values:

default | transaction

Default value:

default

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
lifecycle

Deployment file:

weblogic-ejb-jar.xml

Function

The passivation-strategy element determines whether or not WebLogic Server maintains the intermediate state of entity EJBs in its cache. See Locking and Caching Services for Entity EJBs for more information.

Example

The following entry reverts to WebLogic Server WebLogic Server locking and caching behavior:

<entity-descriptor>

  <lifecycle>

    <passivation-strategy>default</passivation-strategy>

  </lifecycle>

</entity-descriptor>

persistence

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Required only for entity EJBs that use container-managed persistence services.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The persistence stanza defines properties that determine the persistence type, transaction commit behavior, and ejbLoad() and ejbStore() behavior for entity EJBs in WebLogic Server.

Example

<entity-descriptor>

  <persistence>

    <is-modified-method-name>...</is-modified-method-name>

    <delay-updates-until-end-of-tx>...</delay-updates-until-end-of-tx>

    <finders-call-ejbload>...</finders-call-ejbload>

    <persistence-type>...</persistence-type>

    <db-is-shared>false</db-is-shared>

    <persistence-use>...</persistence-use>

  </persistence>

</entity-descriptor>

persistence-type

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Required only for entity EJBs that use container-managed persistence services.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

Deployment file:

weblogic-ejb-jar.xml

Function

The persistence-type stanza defines a persistence service that the entity EJB can use. You can define multiple persistence-type stanzas in weblogic-ejb-jar.xml for testing your EJB with multiple persistence services. Only the persistence type defined in persistence-use is actually used during deployment.

persistence-type includes several elements that identify the persistence type's:

Example

The following excerpt shows a sample persistence-type stanza:

<persistence>

  <persistence-type>

    <type-identifier>WebLogic_CMP_RDBMS</type-identifier>

    <type-version>5.1.0</type-version>

    <type-storage>META-INF\weblogic-cmp-rdbms-jar.xml</type-storage>

  </persistence-type>

</persistence>

persistence-use

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Required only for entity EJBs that use container-managed persistence services.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

Deployment file:

weblogic-ejb-jar.xml

Function

The persistence-use stanza is similar to persistence-type, but it defines the persistence service actually used during deployment. persistence-use uses the type-identifier and type-version elements defined in a persistence-type to identify the service.

Example

To deploy an EJB using the WebLogic Server RDBMS-based persistence service defined in persistence-type, use the following persistence-use stanza:

<persistence-use>

  <type-identifier>WebLogic_CMP_RDBMS</type-identifier>

  <type-version>5.1.0</type-version>

</persistence-use>

persistent-store-dir

Range of values:

Fully qualified filesystem path

Default value:

n/a

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean

stateful-session-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The persistent-store-dir element specifies a file system directory where WebLogic Server stores the state of passivated stateful session bean instances.

Example

See stateful-session-descriptor.

pool

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean
stateless-session-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The pool stanza configures the behavior of WebLogic Server free pool for a stateless session EJB.

Example

The pool stanza can contain the elements shown here:

<stateless-session-descriptor>

  <pool>

    <max-beans-in-free-pool>500</max-beans-in-free-pool>

    <initial-beans-in-free-pool>250</initial-beans-in-free-pool>

  </pool>

</stateless-session-descriptor>

principal-name

Range of values:

valid WebLogic Server principal name

Default value:

n/a

Requirements:

At least one principal-name is required in the security-role-assignment stanza. You may define more than one principal-name for each role-name.

Parent elements:

weblogic-enterprise-bean
security-role-assignment

Deployment file:

weblogic-ejb-jar.xml

Function

principal-name specifies the name of an actual WebLogic Server principal to apply to the specified role-name.

Example

See security-role-assignment.

read-timeout-seconds

Range of values:

0 to maxSeconds

Default value:

0

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
entity-cache

Deployment file:

weblogic-ejb-jar.xml

Function

The read-timeout-seconds element specifies the number of seconds between ejbLoad() calls on a Read-Only entity bean. By default, read-timeout-seconds is set to 0, and WebLogic Server calls ejbLoad() only when the bean is brought into the cache.

Example

The following entry causes WebLogic Server to call ejbLoad() for instances of the AccountBean class only when the instance is first brought into the cache:

<weblogic-enterprise-bean>

  <ejb-name>AccountBean</ejb-name>

  <entity-descriptor>

    <entity-cache>

      <read-timeout-seconds>0</read-timeout-seconds>

    </entity-cache>

  </entity-descriptor>

</weblogic-enterprise-bean>

reference-descriptor

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The reference-descriptor stanza maps references in the ejb-jar.xml file to the JNDI names of actual resource factories and EJBs available in WebLogic Server. The DeployerTool utility simplifies the process of mapping EJB references. You can use DeployerTool to connect to a WebLogic Server and assign available resources before deploying. See Mapping EJB references in Deploying EJBs with DeployerTool for more information.

Example

The reference-descriptor stanza contains one or more additional stanzas to define resource factory references and EJB references. The following shows the organization of these elements:

<reference-descriptor>

  <resource-description>

    ...

  </resource-description>

  <ejb-reference-description>

    ...

  </ejb-reference-description>

</reference-descriptor>

replication-type

Range of values:

InMemory | None

Default value:

None

Requirements:

Optional element. Valid only for stateful session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean
stateful-session-descriptor
stateful-session-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

The replication-type element determines whether or not WebLogic Server replicates the state of stateful session EJBs across WebLogic Server instances in a cluster. If you select InMemory, the state of the EJB is replicated. If you select None, the state is not replicated; this behavior matches that of WebLogic Server Version 5.1.

See In-memory Replication for Stateful Session EJBs for more information.

Example

See stateful-session-clustering.

res-ref-name

Range of values:

a valid resource reference name from the ejb-jar.xml file

Default value:

n/a

Requirements:

Required element if the EJB specifies resource references in ejb-jar.xml

Parent elements:

weblogic-enterprise-bean
reference-description
resource-description

Deployment file:

weblogic-ejb-jar.xml

Function

res-ref-name specifies a resource reference name. This is the reference that the EJB provider places within the ejb-jar.xml deployment file.

Example

See resource-description.

resource-description

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean
reference-description

Deployment file:

weblogic-ejb-jar.xml

Function

The resource-description stanza maps a resource reference named defined in ejb-jar.xml to the JNDI name of an actual resource available in WebLogic Server.

Example

The resource-description stanza can contain additional elements as shown here:

<reference-descriptor>

  <resource-description>

    <res-ref-name>. . .</res-ref-name>

    <jndi-name>...</jndi-name>

  </resource-description>

  <ejb-reference-description>

    <ejb-ref-name>. . .</ejb-ref-name>

    <jndi-name>. . .</jndi-name>

  </ejb-reference-description>

</reference-descriptor>

role-name

Range of values:

an EJB role name defined in ejb-jar.xml

Default value:

n/a

Requirements:

Required element in security-role-assignment.

Parent elements:

weblogic-enterprise-bean
security-role-assignment

Deployment file:

weblogic-ejb-jar.xml

Function

role-name identifies an application role name that the EJB provider placed in the ejb-jar.xml deployment file. Subsequent principal-name elements in the stanza map WebLogic Server principals to the specified role-name.

Example

See security-role-assignment.

security-role-assignment

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Required element if ejb-jar.xml defines application roles.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The security-role-assignment stanza maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.

Example

The security-role stanza can contain one or more of the following elements:

<security-role-assignment>

  <role-name>PayrollAdmin</role-name>

  <principal-name>Tanya</principal-name>

  <principal-name>system</principal-name>

  ...

</security-role-assignment

stateful-session-cache

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

The stateful-session-cache stanza is optional, and is valid only for stateful session EJBs.

Parent elements:

weblogic-enterprise-bean,
stateful-session-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The stateful-session-cache stanza defines properties used to cache stateful session EJB instances within WebLogic Server. See EJB Lifecycle in WebLogic Server for a general discussion of the caching services available in WebLogic Server.

Example

<stateful-session-cache>

  <max-beans-in-cache>...</max-beans-in-cache>

  <idle-timeout-seconds>...</idle-timeout-seconds>

  <read-timeout-seconds>...<read-timeout-seconds>

</stateful-session-cache>

stateful-session-clustering

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element. Valid only for stateful session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
stateful-session-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The stateful-session-clustering stanza contains elements that determine how WebLogic Server replicates stateful session EJB instances in a cluster.

Example

The following excerpt shows the structure of a entity-clustering stanza:

<stateful-session-clustering>

  <home-is-clusterable>true</home-is-clusterable>

  <home-load-algorithm>random</home-load-algorithm>

  <home-call-router-class-name>beanRouter</home-call-router-class-name>

  <replication-type>InMemory</replication-type>

</stateful-session-clustering>

stateful-session-descriptor

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

One stateful-session-descriptor stanza is required for each stateful session EJB in the .jar.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The stateful-session-descriptor stanza defines caching, clustering, and persistence properties for stateful session EJBs in WebLogic Server.

Example

The following example shows the structure of the stateful-session-descriptor stanza:

<stateful-session-descriptor>

  <stateful-session-cache>...</stateful-session-cache>

  <lifecycle>...</lifecycle>

  <persistence>...</persistence>

  <persistent-store-dir>/weblogic/myserver</persistent-store-dir>

  <stateful-session-clustering>...</stateful-session-clustering>

</stateful-session-descriptor>

stateless-bean-call-router-class-name

Range of values:

Valid router class name

Default value:

n/a

Requirements:

Optional element. Valid only for stateless session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

stateless-bean-call-router-class-name specifies the name of a custom class to use for routing bean method calls. This class must implement weblogic.rmi.extensions.CallRouter(). If specified, an instance of this class is called before each method call. The router class has the opportunity to choose a server to route to based on the method parameters. The class returns either a server name or null, which indicates that the current load algorithm should select the server.

Example

See stateless-clustering.

stateless-bean-is-clusterable

Range of values:

true | false

Default value:

true

Requirements:

Optional element. Valid only for stateless session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

When stateless-bean-is-clusterable is "true," the EJB can be deployed from multiple WebLogic Servers in a cluster. Calls to the home stub are load-balanced between the servers on which this bean is deployed, and if a server hosting the bean is unreachable, the call automatically fails over to another server hosting the bean.

Example

See stateless-clustering.

stateless-bean-load-algorithm

Range of values:

round-robin | random | weight-based

Default value:

Value of weblogic.cluster.defaultLoadAlgorithm in weblogic.properties file

Requirements:

Optional element. Valid only for stateless session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

stateless-bean-load-algorithm specifies the algorithm to use for load balancing between replicas of the EJB home. If this property is not defined, WebLogic Server uses the algorithm specified by the server property, weblogic.cluster.defaultLoadAlgorithm.

You can define stateless-bean-load-algorithm as one of the following values:

Example

See stateless-clustering.

stateless-bean-methods-are-idempotent

Range of values:

true | false

Default value:

false

Requirements:

Optional element. Valid only for stateless session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
stateless-session-descriptor
stateless-clustering

Deployment file:

weblogic-ejb-jar.xml

Function

You can set this element to either "true" or "false." Set stateless-bean-methods-are-idempotent to "true" only if the bean is written such that repeated calls to the same method with the same arguments has exactly the same effect as a single call. This allows the failover handler to retry a failed call without knowing whether the call actually completed on the failed server. Setting this property to "true" makes it possible for the bean stub to automatically recover from any failure as long as another server hosting the bean can be reached.

Example

See stateless-clustering.

stateless-clustering

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element. Valid only for stateless session EJBs in a cluster.

Parent elements:

weblogic-enterprise-bean,
stateless-session-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The stateless-clustering stanza contains elements that determine how WebLogic Server replicates stateless session EJB instances in a cluster.

Example

The following excerpt shows the structure of a stateless-clustering stanza:

<stateless-clustering>

  <stateless-bean-is-clusterable>true</stateless-bean-is-clusterable>

  <stateless-bean-load-algorithm>random</stateless-bean-load-algorithm>

  <stateless-bean-call-router-class-name>beanRouter</stateless-bean-call-router-class-name>

  <stateless-bean-methods-are-idempotent>true</stateless-bean-methods-are-idempotent>

</stateless-clustering>

stateless-session-descriptor

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

One stateless-session-descriptor stanza is required for each stateless session EJB in the .jar.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The stateless-session-descriptor stanza defines caching, clustering, and persistence properties for stateless session EJBs in WebLogic Server.

Example

The following example shows the structure of the stateless-session-descriptor stanza:

<stateless-session-descriptor>

  <pool>...</pool>

  <stateless-clustering>...</stateless-clustering>

</stateless-session-descriptor>

transaction-descriptor

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The transaction-descriptor stanza contains elements that define transaction behavior in WebLogic Server. Currently, this stanza includes only one element: trans-timeout-seconds.

Example

The following example shows the structure of the transaction-descriptor stanza:

<transaction-descriptor>

  <trans-timeout-seconds>20</trans-timeout-seconds>

<transaction-descriptor>

transaction-isolation

Range of values:

n/a (XML stanza)

Default value:

n/a (XML stanza)

Requirements:

Optional element.

Parent elements:

weblogic-enterprise-bean

Deployment file:

weblogic-ejb-jar.xml

Function

The transaction-isolation defines method-level transaction isolation settings for an EJB.

Example

The transaction-isolation stanza can contain the elements shown here:

<transaction-isolation>

  <isolation-level>Serializable</isolation-level>

  <method>

    <description>...</description>

    <ejb-name>...</ejb-name>

    <method-intf>...</method-intf>

    <method-name>...</method-name>

    <method-params>...</method-params>

  </method>

</transaction-isolation>

trans-timeout-seconds

Range of values:

0 to maxSeconds

Default value:

300

Requirements:

Optional element. Valid only for entity EJBs.

Parent elements:

weblogic-enterprise-bean,
transaction-descriptor

Deployment file:

weblogic-ejb-jar.xml

Function

The trans-timeout-seconds element specifies the maximum duration for an EJB's container-initiated transactions. If a transaction lasts longer than trans-timeout-seconds, WebLogic Server rolls back the transaction.

If you specify no value for trans-timeout-seconds, container-initiated transactions timeout after five minutes, by default.

Example

See transaction-descriptor.

type-identifier

Range of values:

valid string

Default value:

n/a

Requirements:

Required only for entity EJBs that use container-managed persistence services.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

persistence-type

and

weblogic-enterprise-bean,
entity-descriptor,
persistence

persistence-use

Deployment file:

weblogic-ejb-jar.xml

Function

type-identifier contains text that identifies an entity EJB persistence type. WebLogic Server RDBMS-based persistence uses the identifier, WebLogic_CMP_RDBMS. If you use a different persistence vendor, consult the vendor's documentation for information on the correct type-identifier.

Example

See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.

type-storage

Range of values:

valid string

Default value:

n/a

Requirements:

Required only for entity EJBs that use container-managed persistence services.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

persistence-type

Deployment file:

weblogic-ejb-jar.xml

Function

type-storage defines the full path of the file that stores data for this persistence type. The path must specify the file's location relative to the top level of the EJB's .jar deployment file or deployment directory.

WebLogic Server RDBMS-based persistence generally uses an XML file named weblogic-cmp-rdbms-jar.xml to store persistence data for a bean. This file is stored in the META-INF subdirectory of the .jar file.

Example

See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.

type-version

Range of values:

valid string

Default value:

n/a

Requirements:

Required only for entity EJBs that use container-managed persistence services.

Parent elements:

weblogic-enterprise-bean,
entity-descriptor,
persistence

persistence-type

and

weblogic-enterprise-bean,
entity-descriptor,
persistence

persistence-use

Deployment file:

weblogic-ejb-jar.xml

Function

type-version identifies the version of the specified persistence type.

Note: If you use WebLogic Server RDBMS-based persistence, the specified version must exactly match the RDBMS persistence version for the WebLogic Server release. Specifying an incorrect version results in the error:

weblogic.ejb.persistence.PersistenceSetupException: Error initializing the CMP Persistence Type for your bean: No installed Persistence Type matches the signature of (identifier `Weblogic_CMP_RDBMS', version `version_number').

Example

See persistence-type for an example that shows the complete persistence-type definition for WebLogic Server RDBMS-based persistence.